---
title: ExtractController
summary: Extracts page ranges from a source PDF document.
status: draft
owner: Not determined from source
last_reviewed: 2026-09-17
library: PdfAPI
reference_type: embedded
---

# ExtractController

`ExtractController` extracts one or more page ranges from a source PDF document into a new output document.

| Field | Value |
| --- | --- |
| **Controller** | `ExtractController` |
| **Base** | `System.Web.Http.ApiController` |
| **Route prefix** | `[RoutePrefix("v1")]` |
| **Source** | `PdfAPI\Controllers\v1\ExtractController.cs` |
| **Controller-level authorization** | None in code |
| **Error handling** | Per-action `try`/`catch` + `ILogService.LogException`; response then passes through `ApiResponseHandler`, whose final outer envelope is unknown** ([details](../endpoints.md#error-response-shape)) |
| **Endpoints** | 1 |

---

## POST v1/extract

Validates that the supplied document is a real PDF, then extracts the requested page ranges into a new output document.

| Field | Value |
| --- | --- |
| **HTTP verb** | `POST` |
| **Resolved route** | `v1/extract` |
| **Route composition** | `[RoutePrefix("v1")]` + `[Route("extract")]` |
| **Action** | `ExtractPages(ExtractPagesRequest request)` |
| **Return type** | `IHttpActionResult` (`Ok(result)`) |
| **Authorization** | [None in code](../authentication-authorization.md#authorization-enforcement) |
| **Idempotent** | No — a repeat call can create a new `PDFTracking` record and a new output document* |
| **Operation** | [OP-EXTRACT-PAGES](../operations/op-extract-pages.md) |

### Parameters

| Name | In | Type | Required | Default | Binding | Purpose |
| --- | --- | --- | --- | --- | --- | --- |
| `request` | Body | `PdfAPI.Core.ExtractPagesRequest` | Yes | — | Implicit complex-type body binding* | The source document and the page ranges to extract |

### Request

| Field | Value |
| --- | --- |
| **DTO** | `PdfAPI.Core.ExtractPagesRequest` (`PdfAPI.Core\Request\ExtractPagesRequest.cs`) |
| **Media type** | `application/json` |
| **Validation** | Document validity is checked by [BR-PDFAPI-004](../business-rules.md#br-pdfapi-004-extraction-requires-pdf-validation) before extraction runs |

| Property | Type | Required | Constraints | Purpose |
| --- | --- | --- | --- | --- |
| `DocumentRange` | `DocumentRange` | Yes | — | The source document plus one or more `PageRange` entries |

### Response

| Field | Value |
| --- | --- |
| **DTO** | `PdfAPI.Core.PdfResult` |
| **Media type** | `application/json` |

| Property | Type | Nullable | Purpose |
| --- | --- | --- | --- |
| `Status` | `PdfStatus` | No | Result of the extraction |
| `Document` | `Document` | Yes | The extracted output document |

### Status codes

| Status | Condition | Body |
| --- | --- | --- |
| `200 OK` | Extraction succeeds, or a failure is caught and returned as a failed `PdfResult` | `PdfResult` |

### Errors

| Error status | Trigger | Produced by | Body |
| --- | --- | --- | --- |
| `500 Internal Server Error` | None identified — a `null` `request` is dereferenced only inside the `try` block, and the `catch` tolerates a `null` request when constructing `PdfResult`* | — | — |

### Business rules

- [BR-PDFAPI-004](../business-rules.md#br-pdfapi-004-extraction-requires-pdf-validation) — page extraction validates that the source document is a real PDF before any extraction work.
- [BR-PDFAPI-018](../business-rules.md#br-pdfapi-018-page-range-clamping-and-reversal) — page ranges are clamped to the document's page count, out-of-range ranges are skipped, descending ranges extract pages in reverse order, and a single `IsOriginal` range returns the original file untouched.

### Authorization

No authorization attribute or programmatic check is present. See [Authentication and authorization](../authentication-authorization.md).

### Side effects and idempotency

| Aspect | Finding |
| --- | --- |
| Records written | `PDFTracking`, when tracking is enabled for the request (see [Data model](../data-model.md)) |
| Downstream calls | None identified |
| Files or messages produced | Extracted output document written to `pdfapi.rootdirectory` |
| Repeat-call behavior | Each call produces a new tracking record and a new output document* |

### Example

```http
POST v1/extract HTTP/1.1
Host: <host>
Content-Type: application/json

{
  "DocumentRange": {
    "Document": { "File": "<base64 bytes>" },
    "PageRanges": [ { "StartPage": 1, "StopPage": 3 } ]
  }
}
```

```http
HTTP/1.1 200 OK
Content-Type: application/json

{
  "Status": "Succeeded",
  "Document": { "FileName": "extracted.pdf" }
}
```

---

## Related documentation
- [API index](../index.md)
- [Overview](../overview.md)
- [Architecture](../architecture.md)
- [Endpoints](../endpoints.md)
- [Authentication and authorization](../authentication-authorization.md)
- [Dependencies](../dependencies.md)
- [Configuration](../configuration.md)
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)
- [Data model](../data-model.md)
- [Operational runbook](../operational-runbook.md)
- [Tech debt](../tech-debt.md)

> **Note:** Statements marked with `*` were inferred from code structure, naming conventions, or
> contextual evidence where direct confirmation was not available in source artifacts. Statements
> marked with `**` could not be confirmed; treat as unknown until verified.

## Sources
- PdfAPI\Controllers\v1\ExtractController.cs
- PdfAPI.Core\Request\ExtractPagesRequest.cs
- PdfAPI.Core\Extract\DocumentRange.cs
- PdfAPI.Core\Extract\PageRange.cs
- PdfAPI.Core\PdfResult.cs